/* ******************************************************************************
 * Copyright (c) 2006-2012 XMind Ltd. and others.
 * 
 * This file is a part of XMind 3. XMind releases 3 and
 * above are dual-licensed under the Eclipse Public License (EPL),
 * which is available at http://www.eclipse.org/legal/epl-v10.html
 * and the GNU Lesser General Public License (LGPL), 
 * which is available at http://www.gnu.org/licenses/lgpl.html
 * See http://www.xmind.net/license.html for details.
 * 
 * Contributors:
 *     XMind Ltd. - initial API and implementation
 *******************************************************************************/
package org.xmind.ui.io;

import java.io.IOException;
import java.io.OutputStream;

import org.eclipse.core.runtime.IStatus;

/**
 * An <code>IDownloadTarget</code> describes a location where the download data
 * should be placed.
 * 
 * @author Frank Shaka
 */
public interface IDownloadTarget {

    /**
     * An <code>IDownloadTarget2</code> adds functions that are notified when
     * the donwload job is done.
     * 
     * @author Frank Shaka
     */
    interface IDownloadTarget2 {

        /**
         * Called when the download job is done. Clients can implement this
         * method to perform cleaning or other finishing work.
         * <p>
         * Note that any error generated by this method will be ignored.
         * 
         * @param status
         *            the result of the download job
         */
        void afterDownload(IStatus status);

    }

    /**
     * Returns the path describing this download target. Used to tell the user
     * where the data are to be downloaded.
     * 
     * @return the path describing this download target
     */
    String getPath();

    /**
     * Opens and returns an output stream to which downloaded data are written.
     * Each call to this method should result in a new output stream to be
     * opened.
     * 
     * @return an output stream to receive downloaded data
     * @throws IOException
     *             should any I/O error occurred
     */
    OutputStream openOutputStream() throws IOException;

}
